Перейти к основному содержимому

Тезисное обоснование архитектурных решений

Версия: 1.0 Дата: 25.04.2026 Статус: Утверждён

Каждое нетривиальное архитектурное решение в документации vitiana-api-platform обосновано тезисами в самом документе.

Не «делаем так, потому что лучше». А «делаем так — потому что A, B, C; альтернативы X и Y отклонены по причинам D и E; ограничения F принимаются осознанно».

Это касается всех новых документов, всех существенных правок, и всех структурных решений (декомпозиция, выбор паттерна, выбор стратегии).

Зафиксировано 25.04.2026.

Главный тезис​

Архитектурный документ без обоснования — это утверждение, не решение. Решение должно быть проверяемым и оспариваемым — это требует явных тезисов, альтернатив и компромиссов.

Тезисное обоснование — не бюрократия и не ритуал, а способ:

  • остановить деградацию через «делаем как привыкли»;
  • обнаружить скрытые конфликты с другими документами раньше, чем они материализуются в коде;
  • передать контекст следующему архитектору или разработчику без потерь;
  • защитить решение от размывания при ревью или давлении сроков.

Что входит в тезисное обоснование​

Минимальный набор для любого ключевого решения в документе:

1. Цель решения​

Чему служит это решение в контексте бизнес-целей платформы.

Не «улучшить производительность» (это пустая формулировка), а «сократить latency p99 на partner search до 200мс, чтобы выдерживать SLA для tier-2 партнёров».

2. Тезисы поддержки (3-5 пунктов)​

Конкретные причины выбора. Каждый тезис — самостоятельное утверждение, которое можно проверить или оспорить.

Хорошо:

  • «Каноничная модель не должна зависеть от структур поставщиков, потому что замена supplier должна быть локальным изменением слоя приёма данных.»
  • «Коммерческая фиксация (Quote) должна быть отдельной сущностью, потому что её validity window и applied commercial policy не существуют ни в Offer (нестабильно), ни в Booking (уже завершено).»

Плохо:

  • «Так лучше для масштабируемости.» (без раскрытия)
  • «Это современный подход.» (без объяснения, почему именно этот, и какие альтернативы отклонены)

3. Альтернативы и почему они отклонены​

Минимум 1-2 альтернативы для нетривиальных решений с явным обоснованием отклонения.

Пример:

  • «Альтернатива: использовать одну таблицу entities с типизацией через entity_type для всех canonical-сущностей. Отклонено, потому что (а) теряется query optimization per-domain; (б) усложняется retention policy; (в) governance contour не может вести field-level lineage в untyped storage.»

4. Принимаемые ограничения и trade-off​

Любое решение имеет цену. Эта цена должна быть явно зафиксирована.

Примеры:

  • «Принимаем: рост сложности слоя приёма данных. Это компенсируется тем, что вся остальная платформа изолирована от supplier specifics.»
  • «Принимаем: невозможность простой одиночной миграции в будущем при смене storage. Это компенсируется тем, что storage class разделение позволяет миграцию по slice.»

5. Связь с другими решениями платформы​

Каждое решение работает не в изоляции. Указываю, на какие соседние документы / решения опирается, и что данный выбор поддерживает дальше по цепочке.

Пример:

  • «Опирается на: правило 00000 (платформа задаёт canonical model), domain-model.md (entities), eventing-and-queue-baseline.md (event-driven обновления).»
  • «Поддерживает: commercial-model.md (actor-aware quote), partner-finance-and-clearing.md (commercial commitment trace).»

6. Связь с современными лучшими практиками​

Указываю, на какой индустриальный паттерн опирается решение и почему он применим к нашей задаче.

Пример:

  • «Применяем event sourcing для booking lifecycle, аналогично паттерну в Stripe payment processing. Применим, потому что бронирование имеет схожие требования к audit trail, идемпотентности (idempotency) и replay capability.»

Где обоснование обязательно​

Обязательно (без исключений)​

  • Все решения по доменной модели (domain-model.md и связанные).
  • Все решения по surface contracts (что попадает на agency / partner / B2C / S2S / internal).
  • Все решения по storage policy (truth class, retention, isolation strength).
  • Все решения по event taxonomy и event channel families.
  • Все решения по commercial model (tiers, dynamic pricing, settlement boundaries).
  • Все решения по compliance и legal posture.
  • Все решения по deployment phases и compute packaging.
  • Все решения по multi-tenant isolation strength.

Допустимо без подробного обоснования​

  • Очевидные следствия уже зафиксированных решений.
  • Нумерация, форматирование, стилистика.
  • Ссылки и backlinks.

Как структурировать обоснование в документе​

В каждом крупном документе — раздел ## Обоснование решений или ## Принципы и тезисы.

В каждом разделе доменного решения — подраздел ### Почему именно так с тезисами.

Альтернатива для коротких решений — каждое архитектурное утверждение сопровождается короткой формулировкой **Почему:** сразу под ним. Это работает для коротких решений в текстовом потоке.

Длинные альтернативы — отдельный раздел с явной структурой:

## Почему [решение]

**Цель:** ...

**Тезисы:**
1. ...
2. ...
3. ...

**Альтернативы:**
- A: отклонено, потому что ...
- B: отклонено, потому что ...

**Принимаемые ограничения:**
- ...

**Связь с другими решениями:**
- Опирается на: ...
- Поддерживает: ...

**Современные практики:**
- ...

Запрещённые формулировки​

Документ не публикуется (даже как Черновик), если содержит:

  • «Так принято в индустрии.» — без указания где, почему и применимо ли к нам.
  • «Это просто работает.» — без обоснования.
  • «Все так делают.» — без раскрытия.
  • «Лучшая практика.» — без указания источника и применимости.
  • «Так быстрее.» — без указания, насколько и за счёт чего.
  • «Это очевидно.» — если очевидно, тезис формулируется в одну строку, не пропускается.

Как применять​

Перед публикацией каждого документа задаю вопросы:

  1. Есть ли в документе нетривиальные решения?
  2. Каждое из них обосновано тезисно?
  3. Указаны ли альтернативы и причины отклонения?
  4. Зафиксированы ли trade-off?
  5. Указаны ли связи с другими документами и современными практиками?

Документ без обоснования ключевых решений — переписывается.

При коротком документе или операционной заметке — обоснование в форме **Почему:** строки. При большом доменном документе — отдельный раздел.

В архивных документах (*-old-YYYY-MM-DD.md) — не правится, оставляется как есть.

Связанная документация​